Repository navigation
Conversation
The Known Issues section covers the fresh-Mac-without-Python failure (runtime_install_exit_2) but not its Node analog: the bundled runtime installer exits 1 when no usable Node.js is reachable, and the boot page renders the install-and-repair guidance without a documented recovery path. Add the parallel entry with the bounded search paths, the Finder-versus-nvm visibility caveat and self-service steps, and align the Prerequisites Node bullet with the runtime's actual 22.22.3+ (24 LTS recommended) requirement instead of the dashboard-build-only floor. Fixes loopx-project#9133 Signed-off-by: Lihua <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
动机 / Motivation
受影响群体为:在未安装 Node.js、仅安装低于 22.22.3 版本,或仅通过 nvm/fnm/volta 安装 Node.js 后从 Finder 启动 LoopX Desktop App 的 macOS 用户与排查启动失败的支持人员。更新前:README 仅说明缺少 Python 的退出码 2 排障,且前置条件仅写明 20.19+ / 22.12+,用户遇到 runtime_install_exit_1 时无从定位 Finder PATH 隔离与 22.22.3+ 要求;更新后:Known Issues 对齐既有 Python 条目结构,明确列出错误码、诊断字段、有界搜索路径、nvm/fnm/volta 不可见原因及安装后点击 Repair this version 的自救步骤,Prerequisites 也同步区分运行时与构建门槛。apps/desktop/loopx-control-plane/README.md 精准补充了与实际 Rust/Shell/Python 实现逐项吻合的 Node.js 缺失排障指引和前置条件说明,且不改变任何可执行代码。本 PR 不改变桌面端是否捆绑 Node.js 的产品策略,不修改 runtime_search_path、boot.js 错误提示文案、30 秒环境缓存 TTL 或任何打包构建流程。
改动思路 / Approach
本 PR 响应 Issue #9133 对全新 Mac 启动停在恢复页问题的定性与后续承诺,选择在现有 apps/desktop/loopx-control-plane/README.md 的 Known Issues(紧邻 Python 缺失条目 runtime_install_exit_2)与 Prerequisites 两处原位增补说明,而不改动桌面端不捆绑 Node.js 的既定架构或引导代码。文档改动精准落在桌面分发说明归属文件 apps/desktop/loopx-control-plane/README.md 内,复用既有 Known Issues 版块与 CLI 安装基准,零侵入生产控制面与桌面原生代码。当前 PR 边界为:仅更新 apps/desktop/loopx-control-plane/README.md 中的 Known Issues 与 Prerequisites 说明,不引入任何打包策略、Tauri 缓存清除或运行时行为调整。从长期维护看,新增条目在结构与术语上与既有 Python 排障段落及 docs/guides/installing-loopx.md 完全一致。
具体改动 / Changes
本次改动(exact head ffc582292548e1692f32287d039370875f114b62)仅编辑 apps/desktop/loopx-control-plane/README.md(+33/-1 行),严格对照需求来源 https://github.com/loopx-project/loopx/issues/9133(版本 issue-9133-comment-2026-11-20T10:07:30Z)完成了两项要求:ISSUE-9133-KNOWN-ISSUE(在 Known Issues 新增「Fresh Mac without a usable Node.js stays on the boot screen」)与 ISSUE-9133-PREREQ(在 Prerequisites 中区分运行受管 TypeScript 运行时所需的 22.22.3+ / 推荐 24 LTS 与仅覆盖 dashboard 构建的 20.19+ / 22.12+)。
关键代码讲解
虽本 PR 为纯文档变更,审查已逐行交叉核验其引用的桌面启动与 Node 探测核心符号:
apps/desktop/loopx-control-plane/src-tauri/src/services.rs#L1091-L1124(runtime_search_path):确认在 macOS 下精确按~/.local/bin、/opt/homebrew/bin、/usr/local/bin、/opt/homebrew/opt/node@24/bin、/usr/local/opt/node@24/bin、/opt/homebrew/opt/node@22/bin、/usr/local/opt/node@22/bin及继承进程PATH的顺序拼接,且bundled_runtime.rs#L199与所有受管服务均复用同一函数configure_runtime_environment。apps/desktop/loopx-control-plane/src-tauri/src/bundled_runtime.rs#L171-L285(install_snapshot):确认内置运行时通过scripts/install-local.sh(第 672、883-885 行)运行loopx --format json doctor --deep --installation-only,非零退出映射为runtime_install_exit_{code}。loopx/control_plane/runtime/node_probe.py#L15,L106-L137(probe_node):确认MINIMUM_NODE_VERSION = (22, 22, 3),经shutil.which("node")找不到或版本不足时在loopx/release_candidate.py#L325-L349使必选检查typescript_effect_runtime_ready失败,进而由loopx/cli_commands/doctor.py#L92返回退出码 1(fail-closed)。apps/desktop/loopx-control-plane/src-tauri/src/maintenance.rs#L799-L876(reinstall_bundled_runtime)与static/boot.js#L191-L255:确认Recovery & updates -> Diagnostics准确暴露error_code与environment.node_found/node_version,且点击 Repair this version 后重置runtime_retry并由lib.rs#L230-L312实时监督线程重连同一窗口而无需第二次重启 App;同时scripts/dashboard.sh#L12证实20.19+ or 22.12+确实仅用于 dashboard 构建。
对主干的风险 / Risks
未发现阻塞性缺陷(No blocking findings)。变更不涉及可执行逻辑、公共 API、默认配置或双语 RFC 成对文件,因此无功能回归风险。唯一可指出的非阻塞细节观察是:maintenance.rs#L580,L632-L639 对 desktop_update_status 返回的 environment 诊断块设置了 30 秒缓存(ENVIRONMENT_TTL),而 reinstall_bundled_runtime 本身并不清空该缓存;因此在点击 Repair this version 时安装程序会立即使用最新的 runtime_search_path 重试并重连工作区,但若在 30 秒内紧接着再次失败,Diagnostics 文本中的 environment.node_found / node_version 需等待 TTL 过期或重开 App 才会刷新。该细节不影响自救步骤的正确性,无需阻塞本 PR。
本地独立验证结果(均在 ffc582292548e1692f32287d039370875f114b62 隔离 worktree 完成):
- 相对链接核验(
apps/desktop/loopx-control-plane/README.md内 7 处图片链接):PASS(全部exists=True)。 - 底层安装校验与 Node 探测单测(
tests/test_release_candidate.py、tests/control_plane/test_effect_runtime_node_probe.py、tests/test_doctor_installation_scope.py):PASS(6 passed+50 passed)。 loopx check --scan-path apps/desktop/loopx-control-plane/README.md、双语 RFC 门禁与loopx canary premerge --tier quick(3/3catalog canaries +1/1public boundary):PASS。
我的整体评价 / Verdict
仅修改 apps/desktop/loopx-control-plane/README.md Markdown 文档,未触及前端 HTML/CSS/JS 或任何渲染界面。无(未在全新裸机 macOS 上执行实机 .app 安装点击,已通过源码逐行交叉核验及单元测试替代)。本 PR 对主干长程语义无扰动(long_horizon: preserved),对桌面端首次启动遇阻用户的排障体验有清晰正向改善(user_experience: improved),全部文档陈述、路径、版本要求与错误码均已对照 exact-head 源码逐项核实准确,公私边界与门禁检查全部通过,建议合入。
English verdict: APPROVE — exact head ffc582292548e1692f32287d039370875f114b62 accurately documents runtime_install_exit_1, environment.node_found/node_version, the bounded runtime_search_path, Finder-vs-nvm visibility, self-service repair, and the 22.22.3+ runtime vs 20.19+/22.12+ dashboard-build Node floor (56 passed in underlying release-candidate/node-probe tests, boundary scan and quick premerge PASS; no blocking findings).
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.2-sol · OpenAI · runtime_reported · xhigh
动机 / Motivation
在 macOS 首次打开 LoopX App 的用户,遇到安装退出 1 后需要知道 App 实际找到了哪个 Node 版本。 当 ~/.local/bin/node 先命中且报 22.22.2 时,保留已安装的 Homebrew Node 24,Core 仍报 node_unavailable。把前置入口指向合格 Node 后,同一个探测才通过。 新版说明把 App 的 Node 22.22.3 下限、诊断入口及修复按钮连到真实失败路径。 本次改动补的是 App README 的恢复步骤,现有安装器、路径策略和诊断字段仍由原代码维护。 缺口在于说明只引导安装另一个版本,少了识别并处理优先命中的旧版本这一步。 问题 #9133
改动思路 / Approach
保留 App 的路径顺序和 Core 的资格校验。README 需要让读者根据 App 的探测结果修复它最先命中的入口。 补齐受支持启动配置的解释和手动恢复,沿用已有诊断与修复入口。 终端里执行 node --version 只能验证交互式 shell。App 诊断报告的版本才对应本次修复所用的路径。单独链接安装指南无法指明这个差别。
具体改动 / Changes
审查提交 ffc5822。README 单文件 +33/-1,新增已知问题和自助步骤,更新运行要求。按基线安装指南核查三点。运行版本下限与 Core 一致。App 路径与诊断列出了正确的候选位置和错误字段。旧版本遮蔽时的恢复仍缺少判断和操作。
关键代码讲解
runtime_search_path先排~/.local/bin,再排系统与 Homebrew 通用位置,最后才到 keg 路径和继承的 PATH。路径顺序node_environment报告第一个命中的文件与可解析版本。probe_node检查同一个启动环境里实际选中的可执行文件是否合格。App 诊断 Core 探测- README 的第 2 步把安装
node@24列为可直接修复的操作,前序版本会影响这个结果。自助步骤
对主干的风险 / Risks
[P2] 补上旧 Node 排在新安装之前时的修复步骤。 我用准确头的两段 Rust 路径逻辑和 Core 探测复核了先后顺序。缺少 Node 与只找到 22.22.2 均触发 node_unavailable。真正命中 Node 24.21.0 时,原探测通过。 当 ~/.local/bin/node 先命中且报 22.22.2 时,保留已安装的 Homebrew Node 24,Core 仍报 node_unavailable。把前置入口指向合格 Node 后,同一个探测才通过。 仅安装后序的 Homebrew keg 会让已按说明操作的用户再次收到同一个启动错误。补一条分支:node_found 为 true 但 node_version 过旧或缺失时,先用 App 的路径顺序核对并更新优先命中的 Node。装入后序 keg 不会自动替换前序入口,确认 App 报告了受支持版本再修复。
原 Node 探测与安装诊断 50 项通过。Quick premerge 的 4 项直接和 4 项选定检查均通过。
语义与 CI 对齐
沿用 runtime_install_exit_1、node_found、node_version 和 Core 的 node_unavailable。App 找到文件和 Core 认可版本是两次判断。用前序旧 Node 加后序受支持 keg 检查 README 步骤,再只替换前序入口并验证诊断版本变化。
我的整体评价 / Verdict
求改。这份说明能帮助完全缺少 Node 的用户,补上先命中旧版本的分支后也能覆盖诊断发现不可用版本的用户。这个修复只需要改文档。这次只改 README,App 恢复面板的界面和行为没有 diff。 本轮用 macOS 上的 Rust 路径选择函数与真实 Core Node 探测做配对。未安装 App 或执行 Tauri 修复、重启与重连,也未改本机 Node 安装。
English verdict: REQUEST_CHANGES at ffc5822. Document how to replace the earlier unsupported Node that still wins after a supported keg is installed.
| 1. Check the boot screen error code or Recovery & updates → Diagnostics | ||
| (`error_code: runtime_install_exit_1`, `environment.node_found` / | ||
| `node_version` confirm the missing runtime). | ||
| 2. Install Node.js 22.22.3+ — for example `brew install node` (the keg-only |
There was a problem hiding this comment.
[P2] 说明如何处理优先命中的旧 Node。 在当前 App 路径顺序下,若 ~/.local/bin/node 报 22.22.2,后面已安装的 node@24 不会被选中。实际解析和 Core 探测仍返回 node_unavailable。请在自助步骤里加上 node_found=true 且版本不合格时的操作,先更新 App 实际命中的入口,再用 App 诊断确认版本后重试。
Fixes #9133
Goal / source
Issue #9133 (external report, LoopX 2.3.0 desktop App on a fresh MacBook): first boot stops on the recovery panel with 「安装程序退出(1);App 的启动环境未找到 Node.js…」 and empty report diagnostics.
Characterization (posted on the issue): this is the documented system-prerequisite path, not an M5-specific defect. The bundled-runtime installer runs
scripts/install-local.sh, whosevalidate_release_candidatestep executesloopx doctor --deep --installation-only; the requiredtypescript_effect_runtime_readycheck fails closed whilenodeis missing (loopx/control_plane/runtime/node_probe.pyresolvesnodeviashutil.which), doctor exits 1, the installer exits 1, and the boot page combinesruntime_install_exit_1withenvironment.node_found=false. The App deliberately does not bundle Node (Node.js 22.22.3+, 24 LTS recommended;docs/guides/installing-loopx.md).Current gap
The App README's Known Issues documents the fresh-Mac-without-Python analog (
runtime_install_exit_2) with self-service steps, but has no entry for the Node analog, and its Prerequisites section lists only the dashboard-build Node floor (20.19+/22.12+), which understates the runtime requirement the installed App enforces.Observable result
apps/desktop/loopx-control-plane/README.mdKnown Issues gains 「Fresh Mac without a usable Node.js stays on the boot screen」: cause, error code plus diagnostics fields (environment.node_found/node_version), the boundednodesearch paths, the Finder-versus-nvm/fnm/volta visibility caveat, and install-and-repair self-service steps mirroring the Python entry.Docs-only change; no runtime, packaging or UI behavior changes.
Owning boundary
apps/desktop/loopx-control-plane/README.md(desktop App distribution documentation). No protocol/RFC pair touched, so the bilingual RFC gate is unaffected.Validation
uv run --extra test loopx canary premerge --from-git-diff --git-diff-base upstream/main(from the clean worktree on latestmaineb552a8bb): all direct checks, catalog canaries, risk-profile smokes and the public-boundary scan passed (exit 0), includingloopx check --scan-path apps/desktop/loopx-control-plane/README.md.